SSHClient supports public key authentication. Depending on the requirements of the SSH server, it can be used instead of or alongside password authentication.

To use public key authentication, you need to load a private key file. The component supports the PPK format as generated by the PuTTYgen utility (an RSA and DSA key generation utility). This format was chosen for these reasons:

1. It is easy to create and manipulate keys with the utility.
2. The format is secure.
3. It has good support on Windows.
4. The utility can import keys from different formats to the PPK format.

You can get the puttygen utility from the PuTTY website (direct link: http://the.earth.li/~sgtatham/putty/latest/x86/puttygen.exe).

The PuTTYPrivateKeyFile class implements the PPK file format. Load your private key file into the class by using the Read() method or the constructor. The class takes the data from a Stream object that you supply or from an AbstractFile and a passphrase (if used) to decrypt the private key.

The passphrase can be a string or a byte array (generated by encoding the passphrase string into ASCII bytes).

The Read method will throw an SSHIncorrectPasswordException if the passphrase for the private key is incorrect. It will throw an SSHPublicKeyAuthenticationDataException if the private key file is malformed, uses unsupported algorithms, or if the message authenticity code check for the private key fails when an unencrypted private key file is used.

Once you've successfully loaded your private key file into a PuTTYPrivateKeyFile object, you supply that object to the Authenticate method. The method has a flavor that takes a username string and a ISSHPublicKeyAuthenticationData object. PuTTYPrivateKeyFile implements this interface.

Authenticate() will throw a SSHAuthenticationFailedException if the public key is rejected by the server. Authenticate() will throw a SSHAuthenticationPartialSuccessException if the public key is accepted by the server but more authentications are required. If that happens, you can then call Authenticate again with your username and password to attempt the 'password' authentication method.

PPK files

The PPK file format has multiple versions: 1, 2 and 3. All versions are written as .ppk files. Version 1 files are very old and no longer used in the field. Version 2 files are the most common. Starting with PuTTY version 0.75, version 3 of the file format was introduced. The PuTTYPrivateKeyFile class only supports version 2 files. An exception will be thrown if a version 3 files is loaded by the class.

Using the puttygen utility, it is possible to convert a version 3 PPK file to a version 2 PPK file.

using Xceed.SSH.Client;
using Xceed.SSH.Core;
using Xceed.SSH.Protocols;

using Xceed.FileSystem;

namespace DocumentationExamples.SSH
{
  class PublicKeyAuthentication1
  {
    static void Example()
    {
      string host = "sftptest.dreamhosters.com";
      string username = "snippet_sftp";

      using( SSHClient ssh = new SSHClient() )
      {
        ssh.Connect( host );

        // Get the private key file
        AbstractFile privateKeyFile = new DiskFile( @"D:\MyPrivateKey.ppk" );
        
        // The key file has a passphrase we will need to read it
        string passphrase = "mypassphrase";

        // Create a PuTTYPrivate key file object
        PuTTYPrivateKeyFile privateKey = new PuTTYPrivateKeyFile();

        // Decrypt the key file using the passphrase
        privateKey.Read( privateKeyFile, passphrase );

        try
        {
          // Authenticate using the private key file object we set up
          ssh.Authenticate( username, privateKey );

          /* ... */
        }
        // These exceptions can be thrown by a call to Authenticate()
        catch( SSHIncorrectPasswordException )
        {
          // This means the authentication method is supported by the server but the password
          // was incorrect for the specified username 
          throw;
        }
        catch( SSHAuthenticationPartialSuccessException )
        {
          // This means the authentication was successful but the server requires an additional authentication
          // using another method specified in the exception information
          throw;
        }
        catch( SSHUnsupportedAuthenticationMethodException )
        {
          // This means the authentication method is not supported by the server
          throw;
        }
        catch( SSHAuthenticationFailedException )
        {
          // This means the authentication method failed
          throw;
        }
      }
    }
  }
}

Imports Xceed.SSH.Client
Imports Xceed.SSH.Core
Imports Xceed.SSH.Protocols

Imports Xceed.FileSystem

Namespace DocumentationExamples.SSH
  Friend Class PublicKeyAuthentication1
    Private Shared Sub Example()
      Dim host As String = "sftptest.dreamhosters.com"
      Dim username As String = "snippet_sftp"

      Using ssh As New SSHClient()
        ssh.Connect(host)

        ' Get the private key file
        Dim privateKeyFile As AbstractFile = New DiskFile("D:\MyPrivateKey.ppk")

        ' The key file has a passphrase we will need to read it
        Dim passphrase As String = "mypassphrase"

        ' Create a PuTTYPrivate key file object
        Dim privateKey As New PuTTYPrivateKeyFile()

        ' Decrypt the key file using the passphrase
        privateKey.Read(privateKeyFile, passphrase)

        Try
          ' Authenticate using the private key file object we set up
          ssh.Authenticate(username, privateKey)

          '... 
        ' These exceptions can be thrown by a call to Authenticate()
        Catch e1 As SSHIncorrectPasswordException
          ' This means the authentication method is supported by the server but the password
          ' was incorrect for the specified username 
          Throw
        Catch e2 As SSHAuthenticationPartialSuccessException
          ' This means the authentication was successful but the server requires an additional authentication
          ' using another method specified in the exception information
          Throw
        Catch e3 As SSHUnsupportedAuthenticationMethodException
          ' This means the authentication method is not supported by the server
          Throw
        Catch e4 As SSHAuthenticationFailedException
          ' This means the authentication method failed
          Throw
        End Try
      End Using
    End Sub
  End Class
End Namespace